home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Documentation / Tech Notes & Articles / Recipes / UI & Events / Menus < prev    next >
Encoding:
Text File  |  1995-11-07  |  9.2 KB  |  199 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Recipes
  2.  
  3. Menus
  4. By The OpenDoc Design Team
  5. November, 1995
  6.  
  7.  
  8. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  9. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  10. Mac and OpenDoc are trademarks of Apple Computer, Inc. 
  11.  
  12.  
  13. Introduction
  14.  
  15. This document describes how part editors deal with menus and the menu bar. 
  16.  
  17. The Base Menu Bar
  18.  
  19. The OpenDoc shell application (or a container application) creates an ODMenuBar object and installs it as the base menu bar using ODWindowState::SetBaseMenuBar(). The base menu bar contains the Apple, Document, Edit, Help and Application menus. 
  20.  
  21. Note: A container application might install a reduced menu bar as the base menu bar for embedded parts. When no embedded part is active, the container application would have its full menu bar.
  22.  
  23. Adding Part Menus to the Base Menu Bar
  24.  
  25. When a part is initialized (or when it is first grabbing the menu focus), it should create its own menu bar object by copying the base menu bar using ODWindowState::CopyBaseMenuBar(), and then adding its own menus (menu handles on the Mac OS). 
  26.  
  27. void ClockPart::BuildMenuBar(Environment* ev)
  28. {
  29.     if ((fMenuBar == kODNULL) || !(fMenuBar->IsValid(ev)))
  30.     {
  31.         fMenuBar = fWindowState->CopyBaseMenuBar(ev);
  32.         fMenuBar->AddMenuLast(ev, kClock_FontMenuID, fFontMenu, fPartWrapper);
  33.         fMenuBar->AddMenuLast(ev, kClock_SizeMenuID, fSizeMenu, fPartWrapper);
  34.         fMenuBar->AddMenuLast(ev, kClock_StyleMenuID,fStyleMenu, fPartWrapper);
  35.         fMenuBar->AddMenuLast(ev, kClock_SettingsMenuID, fSettingsMenu, fPartWrapper);
  36.         fMenuBar->AddMenuLast(ev, kClock_ViewMenuID, fViewMenu, fPartWrapper);
  37.  
  38.         fMenuBar->RegisterCommand(ev, cAnalog, kClock_ViewMenuID, 1);
  39.         fMenuBar->RegisterCommand(ev, cDigital, kClock_ViewMenuID, 2);
  40.         fMenuBar->RegisterCommand(ev, cNewView, kClock_ViewMenuID, 4);
  41.         fMenuBar->RegisterCommand(ev, cSynchronize, kClock_SettingsMenuID, 1);
  42.         fMenuBar->RegisterCommand(ev, cShowDisplaySettings, kClock_SettingsMenuID, 2);
  43.         fMenuBar->RegisterCommand(ev, cShowAlarmSettings, kClock_SettingsMenuID, 3);
  44.         fMenuBar->RegisterCommand(ev, cNewFloater, kClock_SettingsMenuID, 4);
  45.         fMenuBar->RegisterCommand(ev, cNewSinker, kClock_SettingsMenuID, 5);
  46.         fMenuBar->RegisterCommand(ev, cNewMenu, kClock_SettingsMenuID, 6);
  47.     }
  48. }
  49.  
  50.  
  51. Note: fFontMenu etc. are menu handles loaded from a resource. See the recipe on handling resources in OpenDoc.
  52.  
  53. New in DR4: If menus are inserted and removed from a menu bar object which is the current displayed menubar, the menu bar is redrawn, so it is not necessary to call ODMenuBar::Display().
  54.  
  55. Registering Command IDs
  56.  
  57. The Mac™ OS does not have position-independent IDs for  menu items. OpenDoc allows part editors to register a position-independent Command ID for each menu and item using ODMenuBar::RegisterCommand().  Ideally, a part editor or part editor framework would capture the mapping from menu items to command IDs in a resource so that the part editor's menus can be rearranged without altering the code or recompiling.
  58.  
  59. The OpenDoc shell registers commands for the items in the Apple, Document and Edit menus, some of which are handled by part editors (eg. Print and View In Window). Part editors can add items to the end of the Document and Edit menus, but are discouraged from reordering the items of the base menu bar. If a part editor does reorganizes those menus, it must reregister the command numbers so that the shell can still handle menu items correctly. 
  60.  
  61. New in DR2:  A range of command IDs from kODCommandShellFirst ( = 1000) to kODCommandShellLast (= 20000) is reserved for OpenDoc shells and container applications. Part editors should use IDs above 20000.
  62.  
  63. New in DR2: Command IDs can also represent menus as a whole (using 0 as the item). The OpenDoc shell registers
  64. kODCommandAppleMenu, kODCommandDocumentMenu and kODCommandEditMenu in addition to the items in those menus. These commands can be used to enable or disable entire menus.
  65.  
  66. Menu IDs
  67.  
  68. Macintosh menu IDs are positive shorts. Negative values are reserved by the System.  Hierarchical menus must be in the 1 byte range.
  69.  
  70. Menu IDs can be the same as the resource ID, but do not have to be. All menus installed in the menu bar must have unique IDs. Thus there is a potential conflict between the shell, shell plug-ins and the active part. The following ranges are reserved:
  71.  
  72.     Container Applications or the OpenDoc Document Shell:     255-16383
  73.     Plug-Ins/Services:                         16384-20000 (dynamically assigned)
  74.     Part Editors:                             20001-32767
  75.  
  76. For hierarchical menus:
  77.  
  78.     Container Applications or the OpenDoc Document Shell:    0-127
  79.     Plug-Ins/Services:                         128-193 (dynamically assigned)
  80.     Part Editors:                             194-254
  81.  
  82. Since there may be multiple plug-ins, they must assign IDs dynamically, by choosing an ID, looking for a menu with that ID, and if one is found, adding 1 to the ID and trying again.
  83.  
  84. New in DR4:  Note that 255 is reserved for the shell, not for hierarchical menus of part editors. There was an inadvertent overlap in the DR3 version of this recipe.
  85.  
  86. Claiming the Menu Bar
  87.  
  88. When a part activates itself, it should request the menu focus (along with other foci). Once the part has the menu focus, it can call ODMenuBar::Display to make its menu bar active. But first it should check if the menu bar is still valid (i.e. the base menu bar has not been changed.) If is has been changed, it should be re-copied.
  89.  
  90. void ClockFrame::Activate(Environment* ev)
  91. {
  92.     if (!fHasFoci)
  93.     {
  94.         ODBoolean succeeded = kODFalse;
  95.                             
  96.         succeeded = fArbitrator->RequestFocusSet(ev, fFocusSet,fFrame);
  97.                 
  98.         if (succeeded)
  99.         {
  100.             fHasFoci = kODTrue;
  101.             fNeedsFoci = kODFalse;
  102.             this->AcquiredRequestedFoci(ev);
  103.         }
  104.     }
  105. }
  106.  
  107. void ClockTimeFrame::AcquiredRequestedFoci(Environment* ev)
  108. {
  109.     this->AcquiredSelectionFocus(ev);
  110.     fClockPart->InstallMenus(ev);
  111. }
  112.  
  113. void ClockPart::InstallMenus(Environment* ev)
  114. {
  115.     this->BuildMenuBar(ev);    
  116.     
  117.     fMenuBar->Display(ev);
  118.     …
  119. }
  120.  
  121.  
  122. Handling Menu Events
  123.  
  124. OpenDoc turns a mouse-down in the menu bar, or a command-key into an event of type kODEvtMenu. The message field of the event contains the menu result value returned by MenuSelect() or MenuKey(). The high word of this value is the menu, the low word is the menu item. The command ID can be obtained by calling ODMenuBar::GetCommand(). If no command has been registered, a synthetic command id is generated.
  125.  
  126. In HandleEvent:
  127.  
  128. ODBoolean ClockTimeFrame::HandleMenuEvent(Environment *ev, ODEventData* event)
  129. {
  130.     ODBoolean wasHandled = kODTrue;
  131.     long menuResult = event->message;
  132.     short menu = HiWord(menuResult);
  133.     short item = LoWord(menuResult);
  134.     ODCommandID command = fClockPart->GetMenuBar()->GetCommand(ev, menu, item);
  135.  
  136.     if (fClockPart->GetMenuBar()->IsCommandSynthetic(ev, command))// Font etc.
  137.     {
  138.         …
  139.     }
  140.     else
  141.     {
  142.         switch (command)
  143.         {
  144.             …
  145.             case kODCommandAbout:
  146.                 fClockPart->ShowAboutBox(ev, fFrame);
  147.                 break;
  148.             case cSynchronize:
  149.                 fClockPart->ShowSynchDialog(ev);
  150.                 break;
  151.             case cShowSettings:
  152.                 fClockPart->ShowSettingsDialog(ev);
  153.                 break;
  154.             default:
  155.                 wasHandled = kODFalse;
  156.                 break;
  157.         }
  158.     }
  159.     return wasHandled;
  160. }
  161.  
  162.  
  163. Changing Menu Appearance
  164.  
  165. When the mouse is clicked in the menu bar, OpenDoc determines which part has the menu focus, and calls Part::AdjustMenus. There are several ODMenuBar methods for changing menu item appearance by command number. A part can also get hold of the menu handle and use Toolbox calls.
  166.  
  167. void  ClockPart::AdjustMenus(Environment *ev, ODFrame* frame)
  168. {
  169.     fMenuBar->EnableCommand(ev, kODCommandViewAsWin, !frame->IsRoot(ev));
  170.     fMenuBar->EnableCommand(ev, kODCommandShowPartsBin, kODTrue);
  171.     …
  172. }
  173.  
  174. Note: Part Editors will also need to disable certain items when a draft is read-only. See the Init Part and Externalize recipe for information on draft permissions.
  175.  
  176. Disabling All Menus
  177.  
  178. When a moveable modal dialog is displayed, all except Apple and Process menus must be disabled, and re-enabled when the dialog is dismissed. The ODMenuBar::DisableAll() and EnableAll() methods can be used for this purpose. If a moveable modal dialog has a text field in it, the Edit menu will need to be enabled for Cut/Copy/Paste, so the part editor might do something like the following, before showing the dialog:
  179.  
  180.         fMenuBar->DisableAll(ev);
  181.         fMenuBar->EnableCommand(ev,  kODCommandEditMenu, kODTrue ) ;
  182.         InvalMenuBar();
  183.  
  184.  
  185. Root Menu Items
  186.  
  187. New in DR2:
  188.  
  189. The Page Setup and Print menu items need to be handled by the root part of the active window, even if an embedded frame is active and has the menu focus.  As a result the Dispatcher calls the root part's HandleEvent method if the part with the menu focus does not handle the event in its HandleEvent method, and provided the two frames involved are different.
  190.  
  191. For symmetry, the AdjustMenus method of the root part of the active window is also called before that of the part with the menu focus, provided the two frames involved are different.
  192.  
  193. Container parts should check if they have the menu focus when adjusting  menu items, and should be careful not to enable root  menu items like Print when embedded.
  194.  
  195. Shared Menu Bar
  196.  
  197. It is possible to use CFM per-context globals to share the menu bar object between several instances of the same part in a single document. The official Sample Part shows one way to do this. You may wish to define your own reference-counted C++ object to hold several such pieces of information that can be shared by multiple instances of a part. See the Shared Utility Windows recipe.
  198.  
  199.